<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Debugger: Watches</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY lang="EN-US">
    <H1><A name="plugin"></A>Debugger: Watches</H1>

    <DIV class="image">
      <IMG alt="" src="images/DebuggerWatchesPlugin.png">
    </DIV>

    <P>Watches refer to expressions which are evaluated each pause in order to monitor the value of
    variables in the target machine state. The watch variables are expressed in Sleigh and
    evaluated in the current thread's context at the current point in time. If the current trace is
    live and at the present, then the necessary target state is retrieved and recorded. The watch
    can be assigned a data type so that the raw data is rendered in a meaningful way. When
    applicable, that data type can optionally be applied to the trace database. Some metadata about
    the watch is also given, e.g., the address of the value.</P>

    <P>The watch window uses colors to hint about changes in and freshness of displayed values. By
    default, changed values are displayed in red, and stale values are displayed in dark grey. A
    <EM>stale</EM> value is one which depends on any register or memory whose contents are not
    known. The value displayed is that computed from the last recorded contents, defaulting to 0
    when never recorded. A <EM>changed</EM> watch is one whose value has just changed. For example,
    if a value changes as result of stepping, then that watch is changed. However, given the
    possibility of rewinding, changing thread focus, etc., "changed" is actually subtly more
    flexible. The watch remembers the evaluation from the user's last coordinates (time, thread,
    frame, etc.) as well as the current coordinates. So, "changed" more precisely refers to a watch
    whose value differs between those two coordinates. This permits the user to switch focus
    between different coordinates and quickly identify what is different.</P>

    <H2>Examples</H2>

    <P>For those less familiar with Sleigh, here are some example expressions:</P>

    <UL>
      <LI><CODE>RSP</CODE>: Display the value of register RSP.</LI>

      <LI><CODE>*:4 0x7fff0004:8</CODE>: Display 4 bytes starting at ram:7fff0004, e.g., to read
      the <CODE>int</CODE> at address 7fff0004. The extraneous but required size specifier on the
      constant 0x7fff0004 is a known issue. Just use the target's pointer size in bytes &mdash; 8
      in the example.</LI>

      <LI><CODE>*:4 my_global</CODE>: Display 4 bytes starting at the label "my_global", e.g., to
      read the <CODE>int</CODE> value there. The label may be in the trace or in a program mapped
      to the trace. Ambiguities are resolved arbitrarily.</LI>

      <LI><CODE>*:8 RSP</CODE>: Display 8 bytes of [ram] starting at the offset given by register
      RSP, e.g., to read a <CODE>long</CODE> on the stack.</LI>

      <LI><CODE>*:4 (RSP+8)</CODE>: Display 4 bytes of [ram] starting 8 bytes after the offset
      given by register RSP, e.g., to read a <CODE>int</CODE> on the stack.</LI>

      <LI><CODE>*:4 ((*:8 RSP)+4)</CODE>: Display 4 bytes of [ram] starting 4 bytes after the
      offset given by reading 8 bytes of [ram] starting at the offset given by register RSP. This
      might be used to read the second <CODE>int</CODE> of an array whose base pointer is on the
      stack.</LI>
    </UL>

    <H2>Table Columns</H2>

    <P>The table displays and allows modification of each watch. It has the following columns:</P>

    <UL>
      <LI>Expression - the user-modifiable Sleigh expression defining this watch.</LI>

      <LI>Address - when evaluation succeeds, the address of the watch's value. This field is
      really only meaningful when the outermost operator of the expression is a memory dereference.
      Double-clicking this cell will navigate the primary dynamic listing to this address, if
      possible.</LI>

      <LI>Symbol - the symbol best representing the address, if applicable. When the watch has an
      address in memory, this will search the trace for a symbol at that address, preferring the
      primary. If no such symbol exists, it will search in the mapped static program, if there is
      one, again preferring the primary symbol. Finally, it will search for a containing function
      in the mapped program.</LI>

      <LI>Value - the raw bytes of the watched buffer. If the expression is a register, then this
      is its hexadecimal value. This field is user modifiable when the <B>Enable Edits</B> toggle
      is on, and the variable is modifiable. Edits may be directed toward a live target, the trace,
      or the emulator. If the value has changed since the last navigation event, this cell is
      rendered in <FONT color="red">red</FONT>.</LI>

      <LI>Type - the user-modifiable type of the watch. Note the type is not marked up in the
      trace. Clicking the <A href="#apply_data_type">Apply Data Type</A> action will apply it to
      the current trace, if possible.</LI>

      <LI>Representation - the value of the watch as interpreted by the selected data type. If the
      value is an address, i.e., Type is a pointer, then double-clicking this cell will navigate
      the primary dynamic listing, if possible. This field is user-modifiable whenever the Value
      column is modifiable and the selected data type provides an encoder.</LI>

      <LI>Error - if an error occurs during compilation or evaluation of the expression, that error
      is rendered here. Double-clicking the row will display the stack trace. Note that errors
      during evaluation can be a very common occurrence, especially as contexts change, and should
      not necessarily cause alarm. An expression devised for one context may not have meaning under
      another, even if it evaluates without error. E.g., <CODE>RIP</CODE> will disappear when
      switching to a 32-bit trace, or <CODE>*:8 (*:8 (RSP+8))</CODE> may cause an invalid
      dereference when the stack pointer moves.</LI>
    </UL>

    <H2>Actions</H2>

    <P>The watches window provides the following actions:</P>

    <H3><A name="apply_data_type"></A>Apply Data to Listing</H3>

    <P>This action is available when there's an active trace, and at least one watch with an
    address and data type is selected. If so, it applies that data type to the value in the
    listing. That is, it attempts to apply the selected data type to the evaluated address, sizing
    it to the value's size.</P>

    <H3><A name="type_settings"></A>Watch Type Settings</H3>

    <P>This action is available on the context menu when there is a single watch selected with a
    data type assigned. It permits the adjustment of that data type's settings, e.g., to display
    decimal vs. hexadecimal.</P>

    <H3><A name="select_addresses"></A>Select Range</H3>

    <P>This action is available when there's an active trace, and at least one watch with memory
    addresses is selected. It selects the memory range comprising the resulting value. This only
    works when the outermost operator of the expression is a memory dereference. It selects the
    range at the address of that dereference having the size of the dereference. For example, the
    expression <CODE>*:8 RSP</CODE> would cause 8 bytes of memory, starting at the offset given by
    RSP, to be selected in the dynamic listing.</P>

    <H3><A name="select_reads"></A>Select Reads</H3>

    <P>This action is available when there's an active trace, and at least one watch with memory
    reads is selected. It selects all memory ranges dereferenced in the course of expression
    evaluation. This can be useful when examining a watch whose value seems unusual. For example,
    the expression <CODE>*:8 RSP</CODE> would cause 8 bytes of memory, starting at the offset given
    by RSP, to be selected in the dynamic listing -- the same result as Select Range. However, the
    expression <CODE>*:4 (*:8 RSP)</CODE> would cause two ranges to be selected: 8 bytes starting
    at RSP and 4 bytes starting at the offset given by <CODE>*:8 RSP</CODE>.</P>

    <H3><A name="add"></A>Add</H3>

    <P>This action is always available. It adds a blank watch to the table. Modify the expression
    to make the entry useful.</P>

    <H3><A name="watch"></A>Watch</H3>

    <P>This action is available in context menus for addresses, selections, or registers. It adds
    the selected item(s) to the watch table. If the context is derived from a static view, it first
    attempts to map it to the current trace. For selections, it adds a typeless watch for each
    range. For single-address locations derived from a listing, it adds a typed watch on the
    current code unit. For other single-address locations, it adds a 1-byte typeless watch on the
    address. For registers, it adds a watch on that register. Note that <CODE>contextreg</CODE> and
    its children cannot be watched, due to a limitation in Sleigh.</P>

    <H3><A name="remove"></A>Remove</H3>

    <P>This action is available when at least one watch is selected. It removes those watches.</P>

    <H3><A name="enable_edits"></A>Enable Edits</H3>

    <P>This toggle is a write protector for machine state. To modify a watch's value, this toggle
    must be enabled. Edits are directed according the to <A href=
    "help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control and Machine State
    Plugin</A>.</P>
  </BODY>
</HTML>
